promise

What is promise?

The 'promise' npm package provides a robust library for working with promises in JavaScript. It allows for the creation, manipulation, and composition of promises for asynchronous operations. It offers features such as deferreds, helpers for common patterns, and methods for controlling the flow of promise chains.

What are promise's main functionalities?

Creating a new Promise

This feature allows you to create a new promise. The constructor takes a function that contains the asynchronous operation. The function provides two arguments, resolve and reject, which are used to settle the promise.

var Promise = require('promise');

var promise = new Promise(function (resolve, reject) {
  // Asynchronous operation here
  if (/* operation successful */) {
    resolve('Success!');
  } else {
    reject(Error('Failure.'));
  }
});

Promise Chaining

Promise chaining enables you to link together multiple asynchronous operations. Each .then() returns a new promise, allowing for further chaining. The .catch() method is used for error handling.

promise.then(function(result) {
  console.log(result); // 'Success!'
  return 'Another value';
}).then(function(result) {
  console.log(result); // 'Another value'
}).catch(function(error) {
  console.error(error);
});

Deferreds

Deferreds provide a way to expose the resolve and reject functions of a promise outside of its constructor. This can be useful when the resolution of a promise needs to be controlled externally.

var deferred = Promise.defer();

deferred.promise.then(function(result) {
  console.log(result);
});

deferred.resolve('Deferred success!');

Promise.all

Promise.all is used to wait for all promises in an iterable to be resolved. The resulting promise is resolved with an array of the resolved values from the passed promises.

var p1 = Promise.resolve(3);
var p2 = 1337;
var p3 = new Promise(function (resolve, reject) {
  setTimeout(resolve, 100, 'foo');
});

Promise.all([p1, p2, p3]).then(function(values) {
  console.log(values); // [3, 1337, 'foo']
});

Promise.race

Promise.race is used to wait only for the first promise to be resolved or rejected. It resolves or rejects with the value from that promise.

var p1 = new Promise(function(resolve, reject) { 
    setTimeout(resolve, 500, 'one'); 
});
var p2 = new Promise(function(resolve, reject) { 
    setTimeout(resolve, 100, 'two'); 
});

Promise.race([p1, p2]).then(function(value) {
  console.log(value); // 'two'
});

Other packages similar to promise

bluebird

Bluebird is a fully-featured promise library with a focus on innovative features and performance. It includes utilities for concurrency, such as Promise.map and Promise.reduce, and has better performance benchmarks compared to 'promise'.

q

Q is one of the earliest promise libraries that brought the concept of promises to Node.js. It has a similar API to 'promise' but also includes a long stack trace feature which is useful for debugging.

when

When is a lightweight promise library that offers an extensive set of tools for creating and composing promises. It is similar to 'promise' but also provides additional features like when.map for concurrency control.

es6-promise

ES6-Promise is a polyfill for the ES6 Promise specification. It provides the basic functionality of promises and is meant to be a lightweight and efficient implementation of the standard, similar to 'promise' but with a focus on ES6 compatibility.

README

promise

This is a simple implementation of Promises. It is a super set of ES6 Promises designed to have readable, performant code and to provide just the extensions that are absolutely necessary for using promises today.

For detailed tutorials on its use, see www.promisejs.org

Installation

Server:

$ npm install promise

Client:

You can use browserify on the client, or use the pre-compiled script that acts as a polyfill.

<script src="https://www.promisejs.org/polyfills/promise-6.1.0.js"></script>

Note that the es5-shim must be loaded before this library to support browsers pre IE9.

<script src="https://cdnjs.cloudflare.com/ajax/libs/es5-shim/3.4.0/es5-shim.min.js"></script>

Usage

The example below shows how you can load the promise library (in a way that works on both client and server). It then demonstrates creating a promise from scratch. You simply call new Promise(fn). There is a complete specification for what is returned by this method in Promises/A+.

var Promise = require('promise');

var promise = new Promise(function (resolve, reject) {
  get('http://www.google.com', function (err, res) {
    if (err) reject(err);
    else resolve(res);
  });
});

API

Before all examples, you will need:

var Promise = require('promise');

new Promise(resolver)

This creates and returns a new promise. resolver must be a function. The resolver function is passed two arguments:

1. resolve should be called with a single argument. If it is called with a non-promise value then the promise is fulfilled with that value. If it is called with a promise (A) then the returned promise takes on the state of that new promise (A).
2. reject should be called with a single argument. The returned promise will be rejected with that argument.

Static Functions

These methods are invoked by calling Promise.methodName.

Promise.resolve(value)

(deprecated aliases: Promise.from(value), Promise.cast(value))

Converts values and foreign promises into Promises/A+ promises. If you pass it a value then it returns a Promise for that value. If you pass it something that is close to a promise (such as a jQuery attempt at a promise) it returns a Promise that takes on the state of value (rejected or fulfilled).

Promise.all(array)

Returns a promise for an array. If it is called with a single argument that Array.isArray then this returns a promise for a copy of that array with any promises replaced by their fulfilled values. Otherwise it returns a promise for an array that conatins its arguments, except with promises replaced by their resolution values. e.g.

Promise.all([Promise.resolve('a'), 'b', Promise.resolve('c')])
  .then(function (res) {
    assert(res[0] === 'a')
    assert(res[1] === 'b')
    assert(res[2] === 'c')
  })

Promise.all(Promise.resolve('a'), 'b', Promise.resolve('c'))
  .then(function (res) {
    assert(res[0] === 'a')
    assert(res[1] === 'b')
    assert(res[2] === 'c')
  })

Promise.denodeify(fn)

Non Standard

Takes a function which accepts a node style callback and returns a new function that returns a promise instead.

e.g.

var fs = require('fs')

var read = Promise.denodeify(fs.readFile)
var write = Promise.denodeify(fs.writeFile)

var p = read('foo.json', 'utf8')
  .then(function (str) {
    return write('foo.json', JSON.stringify(JSON.parse(str), null, '  '), 'utf8')
  })

Promise.nodeify(fn)

Non Standard

The twin to denodeify is useful when you want to export an API that can be used by people who haven't learnt about the brilliance of promises yet.

module.exports = Promise.nodeify(awesomeAPI)
function awesomeAPI(a, b) {
  return download(a, b)
}

If the last argument passed to module.exports is a function, then it will be treated like a node.js callback and not parsed on to the child function, otherwise the API will just return a promise.

Prototype Methods

These methods are invoked on a promise instance by calling myPromise.methodName

Promise#then(onFulfilled, onRejected)

This method follows the Promises/A+ spec. It explains things very clearly so I recommend you read it.

Either onFulfilled or onRejected will be called and they will not be called more than once. They will be passed a single argument and will always be called asynchronously (in the next turn of the event loop).

If the promise is fulfilled then onFulfilled is called. If the promise is rejected then onRejected is called.

The call to .then also returns a promise. If the handler that is called returns a promise, the promise returned by .then takes on the state of that returned promise. If the handler that is called returns a value that is not a promise, the promise returned by .then will be fulfilled with that value. If the handler that is called throws an exception then the promise returned by .then is rejected with that exception.

Promise#catch(onRejected)

Sugar for Promise#then(null, onRejected), to mirror catch in synchronous code.

Promise#done(onFulfilled, onRejected)

Non Standard

The same semantics as .then except that it does not return a promise and any exceptions are re-thrown so that they can be logged (crashing the application in non-browser environments)

Promise#nodeify(callback)

Non Standard

If callback is null or undefined it just returns this. If callback is a function it is called with rejection reason as the first argument and result as the second argument (as per the node.js convention).

This lets you write API functions that look like:

function awesomeAPI(foo, bar, callback) {
  return internalAPI(foo, bar)
    .then(parseResult)
    .then(null, retryErrors)
    .nodeify(callback)
}

People who use typical node.js style callbacks will be able to just pass a callback and get the expected behavior. The enlightened people can not pass a callback and will get awesome promises.

Extending Promises

There are three options for extending the promises created by this library.

Inheritance

You can use inheritance if you want to create your own complete promise library with this as your basic starting point, perfect if you have lots of cool features you want to add. Here is an example of a promise library called Awesome, which is built on top of Promise correctly.

var Promise = require('promise');
function Awesome(fn) {
  if (!(this instanceof Awesome)) return new Awesome(fn);
  Promise.call(this, fn);
}
Awesome.prototype = Object.create(Promise.prototype);
Awesome.prototype.constructor = Awesome;

//Awesome extension
Awesome.prototype.spread = function (cb) {
  return this.then(function (arr) {
    return cb.apply(this, arr);
  })
};

N.B. if you fail to set the prototype and constructor properly or fail to do Promise.call, things can fail in really subtle ways.

Wrap

This is the nuclear option, for when you want to start from scratch. It ensures you won't be impacted by anyone who is extending the prototype (see below).

function Uber(fn) {
  if (!(this instanceof Uber)) return new Uber(fn);
  var _prom = new Promise(fn);
  this.then = _prom.then;
}

Uber.prototype.spread = function (cb) {
  return this.then(function (arr) {
    return cb.apply(this, arr);
  })
};

Extending the Prototype

In general, you should never extend the prototype of this promise implimenation because your extensions could easily conflict with someone elses extensions. However, this organisation will host a library of extensions which do not conflict with each other, so you can safely enable any of those. If you think of an extension that we don't provide and you want to write it, submit an issue on this repository and (if I agree) I'll set you up with a repository and give you permission to commit to it.

License

MIT